3 Customization

Htmlfontify provides the following variable and customization entries:

hfy-link-style-fun

Set this to a function, which will be called with one argument (a ‘{ foo: bar; …}’ CSS style-string)—it should return a copy of its argument, altered so as to make any changes you want made for text which is a hyperlink, in addition to being in the class to which that style would normally be applied.

hfy-html-quote-regex

Regex to match (with a single back-reference per match) strings in HTML which should be quoted with hfy-html-quote (and see hfy-html-quote-map) to make them safe.

hfy-page-footer

As hfy-page-header, but generates the output footer (and takes only 1 argument, the filename).

hfy-display-class

Display class to use to determine which display class to use when calculating a face’s attributes. This is useful when, for example, you are running Emacs on a tty or in batch mode, and want Htmlfontify to have access to the face spec you would use if you were connected to an X display.

Some valid class specification elements are:

  (class      color)
  (class      grayscale)
  (background dark)
  (background light)
  (type       x-toolkit)
  (type       tty)
  (type       motif)
  (type       lucid)

Multiple values for a tag may be combined, to indicate that any one or more of these values in the specification key constitutes a match. For example, ((class color grayscale) (type tty)) would match any of:

  ((class color))
  ((class grayscale))
  ((class color grayscale)))
  ((class color foo))
  ((type  tty))
  ((type  tty) (class color))

hfy-page-header

Function called with two arguments (the filename relative to the top level source directory being etagged and fontified), and a string containing the ‘<style>…</style>’ text to embed in the document—the string returned will be used as the header for the htmlfontified version of the source file.

See also: hfy-page-footer

hfy-src-doc-link-style

String to add to the ‘<style> a’ variant of an Htmlfontify CSS class.

hfy-split-index

Whether or not to split the index hfy-index-file alphabetically on the first letter of each tag. Useful when the index would otherwise be large and take a long time to render or be difficult to navigate.

hfy-find-cmd

The “find” command used to harvest a list of files to attempt to fontify.

hfy-extn

File extension used for output files.

hfy-default-face-def

Fallback defface specification for the face default, used when hfy-display-class has been set (the normal Htmlfontify way of extracting potentially non-current face information doesn’t necessarily work for default).

For example, I customize this to:

((t :background "black" :foreground "white" :family "misc-fixed"))

hfy-init-kludge-hooks

List of functions to call when starting htmlfontify-buffer to do any kludging necessary to get highlighting modes to behave as you want, even when not running under a window system.

hfy-shell-file-name

Should be set to a Bourne compatible shell, which will be invoked for the more complex shell interactions needed by Htmlfontify. Currently this is only required/used when using GNU etags, see hfy-etags-cmd-alist for details.

hfy-optimizations

Optimizations to turn on. So far, the following have been implemented:

merge-adjacent-tags

If two (or more) span tags are adjacent, identical and separated by nothing more than whitespace, they will be merged into one span.

zap-comment-links

Suppress hyperlinking of tags found in comments.

zap-string-links

Suppress hyperlinking of tags found in strings.

div-wrapper

Add ‘<div class="default"> </div>’ tags around the fontified body. (Some people like this because they cut and paste the html into a page with different colors than the fontified code.)

keep-overlays

Preserve overlay highlighting (cf. ediff or goo-font-lock) as well as basic faces. Can result in extremely verbose highlighting if there are many overlays (as is the case with goo-font-lock).

And the following are planned but not yet available:

kill-context-leak

Suppress hyperlinking between files highlighted by different modes.

Note: like compiler optimizations, these optimize the output of the code, not the processing of the source itself, and are therefore likely to slow Htmlfontify down, at least a little. Except for skip-refontification, which can never slow you down, but may result in incomplete fontification.

hfy-src-doc-link-unstyle

Regex to remove from the ‘<style> a’ variant of an Htmlfontify CSS class.

hfy-link-extn

File extension used for href links—useful where the Htmlfontify output files are going to be processed again, with a resulting change in file extension. If nil, then any code using this should fall back to hfy-extn.

hfy-istext-command

Command to run with the name of a file, to see whether it is a text file or not. The command should emit a string containing the word ‘text’ if the file is a text file, and a string not containing ‘text’ otherwise.

hfy-etags-cmd-alist

An alist of possible shell commands that will generate etags output that Htmlfontify can use. ‘%s’ will be replaced by hfy-etags-bin.

hfy-etags-bin

The location of the etags binary (we begin by assuming it’s in your path).

Note that if etags is not in your path, you will need to alter the shell commands in hfy-etags-cmd-alist.

[As of version 0.17, this requirement has been removed: it should all just work(tm).]

hfy-etags-cmd

An etags shell command to run in the source directory to generate a tags file for the whole source tree from there on down. The command should emit the etags output on standard output.

Two canned commands are provided—they drive Emacs’s etags and exuberant-ctags’s etags respectively.

hfy-etag-regex

Regex used to parse an etags entry: must have 3 subexps, corresponding, in order, to:

1. The tag
2. The line
3. The character (point) at which the tag occurs

hfy-index-file

Name (sans extension) of the index file produced during fontification-and-hyperlinking.

hfy-instance-file

Name (sans extension) of the tag usage index file produced during fontification-and-hyperlinking.

hfy-html-quote-map

An alist of character -> entity mappings used to make the text html-safe.